home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / MENUA.HDR < prev    next >
Text File  |  1994-04-25  |  4KB  |  103 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _MenuA(nMenuTopRow, nMenuLeftCol, nMenuMaxItems, cMenuTitle, cMenuArray,
  8. lMsgDisable, lClkDisable) --> nSelection
  9.  
  10. PARAMETERS:
  11.  
  12. nMenuTopRow   : Menu Top Left ROW
  13. nMenuLeftCol  : Menu Top Left COLUMN
  14. nMenuMaxItems : Maximum number of items on menu at once
  15. cMenuTitle    : Menu Title
  16. cMenuArray    : Array of Menu Elements
  17. lMsgDisable   : Logical - Disable InterApp Messages (Default NO)
  18. lClkDisable   : Logical - Disable Clock (Default NO)
  19.  
  20. (lMsgDisable and lClkDisable are reserved for future use.)
  21.  
  22. SHORT:
  23.  
  24. Genral purpose menuing facility.
  25.  
  26. DESCRIPTION:
  27.  
  28. _MenuA() is a general purpose menuing facility.  It's operation is similar
  29. to _Menu().  In _MenuA(), however, the length of the menu can be specified
  30. and any extra menu items are scrolled through this "window".  _Menu()
  31. simply forces the menu size to fit all elements, _MenuA() can display
  32. any number of elements by scrolling the extras "achoice style."
  33.  
  34. It accepts as a parameter an array of character strings to be used as
  35. menu items.  It builds the menu, prompts for a selection and returns
  36. the number of the element selected as it's return value.  If ESC is
  37. pressed, it returns ZERO.
  38.  
  39. nMenuTopRow and nMenuTopLeftCol are the row/col coordinates for the top
  40. left corner of the menu.
  41.  
  42. nMenuMaxItems is the number of items displayable without scrolling to display
  43. more. It is the number of lines that will appear on the menu.  Unlike
  44. _Menu(), _MenuA() fits the menu to the window.  This means that any menu
  45. whose elements do not fit within the limits of the given coordinates will
  46. instead of spilling over, scroll within those coordinates.  For that reason
  47. it is possible to create "ugly" or inefficient menus by specifying a value
  48. for nMaxItems that is greater than the number of items in the menu array.
  49. (You will end up with a window larger than is necessary to hold the menu
  50. items and will have empty space after the last menu element.)
  51.  
  52. lMsgDisable, if TRUE, will disable other apps/users messages being presented.
  53.  
  54. lClkDisable, if TRUE, will disable the real time clock.  The real time
  55. clock is specifically placed on the screen to be used with _FScreen().  If
  56. you are not using _FScreen(), you may want to disable the clock.
  57.  
  58. The most notable difference between _Menu() and _MenuA(), aside from
  59. scrollable menus, is the fact that _MenuA() can receive station messages sent
  60. through the _Kmenu() menu system, whereas _Menu() cannot.  _MenuA() polls for
  61. messages upon any menu activity (i.e., when arrow keys are pressed to move
  62. the menu highlight bar).
  63.  
  64. APPMSG.DAT (the default name for the message file) is NOT created when
  65. the program polls for messages.  AppMsg must be manually created, or
  66. created by a call to __InitAppMsg().  The reason for this is to avoid
  67. overhead and unnecessary APPMSG files in apps that are not going to
  68. use inter-application messaging.
  69.  
  70. See _KMenu() for information on inter-application messaging.
  71.  
  72. NOTE:
  73.  
  74. This function is the engine of _KMENU() which manages menu configurations
  75. external to the program (in data files) and makes calls to _MenuA() to
  76. display menus.
  77.  
  78. EXAMPLE:
  79.  
  80. LOCAL acMainMenu[5]
  81.  
  82.  
  83. acMainMenu[1] = ' Menu Option One   '
  84. acMainMenu[2] = ' Menu Option Two   '
  85. acMainMenu[3] = ' Menu Option Three '
  86. acMainMenu[4] = ' Menu Option Four  '
  87. acMainMenu[5] = ' Menu Option Five  '
  88.  
  89.  
  90. nMenuOpt = _MenuA(10,10,3,'MAIN MENU','acMainMenu')
  91.  
  92.  
  93. Result: A light-bar menu is displayed with the array elements 1 - 3 in
  94. acMainMenu[] as selectable options.  The remaining options can be seen by
  95. pressing the up or down arrow keys (also PgUp/ PgDn keys) to get to them.
  96.  
  97. Once an item is selected, the number of that option is returned as it's
  98. return value.
  99.  
  100. The TOP LEFT corner of the menu is at ROW 10, COL 10.
  101.  
  102. ******************************************************************************/
  103.